.TH std::basic_ostream::operator<< 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_ostream::operator<< \- std::basic_ostream::operator<<

.SH Synopsis
   basic_ostream& operator<<( bool value );                          \fB(1)\fP
   basic_ostream& operator<<( long value );                          \fB(2)\fP
   basic_ostream& operator<<( unsigned long value );                 \fB(3)\fP
   basic_ostream& operator<<( long long value );                     \fB(4)\fP  \fI(since C++11)\fP
   basic_ostream& operator<<( unsigned long long value );            \fB(5)\fP  \fI(since C++11)\fP
   basic_ostream& operator<<( double value );                        \fB(6)\fP
   basic_ostream& operator<<( long double value );                   \fB(7)\fP
   basic_ostream& operator<<( const void* value );                   \fB(8)\fP
   basic_ostream& operator<<( const volatile void* value );          \fB(9)\fP  (since C++23)
   basic_ostream& operator<<( std::nullptr_t );                      \fB(10)\fP \fI(since C++17)\fP
   basic_ostream& operator<<( short value );                         \fB(11)\fP
   basic_ostream& operator<<( int value );                           \fB(12)\fP
   basic_ostream& operator<<( unsigned short value );                \fB(13)\fP
   basic_ostream& operator<<( unsigned int value );                  \fB(14)\fP
   basic_ostream& operator<<( float value );                         \fB(15)\fP
   basic_ostream& operator<<( /* extended-floating-point-type */     \fB(16)\fP (since C++23)
   value );
   basic_ostream& operator<<( std::basic_streambuf<CharT, Traits>*   \fB(17)\fP
   sb );
   basic_ostream& operator<<(                                        \fB(18)\fP
       std::ios_base& (*func)(std::ios_base&) );
   basic_ostream& operator<<(
       std::basic_ios<CharT, Traits>& (*func)(std::basic_ios<CharT,  \fB(19)\fP
   Traits>&) );
   basic_ostream& operator<<(

       std::basic_ostream<CharT, Traits>& (*func)                    \fB(20)\fP

           (std::basic_ostream<CharT, Traits>&) );

   Inserts data into the stream.

   1-8) Inserts value.
   This function behaves as a FormattedOutputFunction. After constructing and checking
   the sentry object, inserts a value by calling std::num_put::put(). If the end of
   file condition was encountered during output (put().failed() == true), sets badbit.
   9) Equivalent to return operator<<(const_cast<const void*>(p));.
   10) Equivalent to return *this << s;, where s is an implementation-defined
   null-terminated character type string.
   11) Inserts a value from short value.
   This function behaves as a FormattedOutputFunction. After constructing and checking
   the sentry object, inserts a long value lval as in \fB(2)\fP, where lval is
     * static_cast<long>(static_cast<unsigned short>(value)), if flags() &
       std::ios_base::basefield is std::ios_base::oct or std::ios_base::hex, or
     * static_cast<long>(value) otheriwse.
   12) Inserts a value from int value.
   This function behaves as a FormattedOutputFunction. After constructing and checking
   the sentry object, inserts a long value lval as in \fB(2)\fP, where lval is
     * static_cast<long>(static_cast<unsigned int>(value)), if flags() &
       std::ios_base::basefield is std::ios_base::oct or std::ios_base::hex, or
     * static_cast<long>(value) otheriwse.
   13,14) Inserts a value from unsigned short or unsigned int value.
   This function behaves as a FormattedOutputFunction. After constructing and checking
   the sentry object, inserts static_cast<unsigned long>(value) as in \fB(3)\fP.
   15) Inserts a value from float value.
   This function behaves as a FormattedOutputFunction. After constructing and checking
   the sentry object, inserts static_cast<double>(value) as in \fB(6)\fP.
   16) Inserts a value from value. The library provides overloads for all
   cv-unqualified extended floating-point types as the type of the parameter value.
   This function behaves as a FormattedOutputFunction. After constructing and checking
   the sentry object, checks the floating-point conversion rank of /*
   extended-floating-point-type */:
     * If the rank is less than or equal to that of double, inserts
       static_cast<double>(value) as in \fB(6)\fP.
     * Otherwise, if the rank is less than or equal to that of long double, inserts
       static_cast<long double>(value) as in \fB(7)\fP.
     * Otherwise, an invocation of this overload is conditionally supported with
       implementation-defined semantics.
   17) This function behaves as an UnformattedOutputFunction. After constructing and
   checking the sentry object, checks if sb is a null pointer. If it is, executes
   setstate(badbit) and exits. Otherwise, extracts characters from the input sequence
   controlled by sb and inserts them into *this until one of the following conditions
   are met:

     * end-of-file occurs on the input sequence;
     * inserting in the output sequence fails (in which case the character to be
       inserted is not extracted);
     * an exception occurs (in which case the exception is caught).
   If no characters were inserted, executes setstate(failbit). If an exception was
   thrown while extracting, sets failbit and, if failbit is set in exceptions(),
   rethrows the exception.
   18-20) Calls func(*this). These overloads are used to implement output I/O
   manipulators such as std::endl.

.SH Parameters

   value - integer, floating-point, boolean, or pointer value to insert
   func  - function to call
   sb    - pointer to the stream buffer to read the data from

.SH Return value

   1-19) *this
   20) func(*this)

.SH Notes

   There are no overloads for pointers to non-static members
   , pointers to volatiles,
   (until C++23) or function pointers (other than the ones with signatures accepted by
   the (18-20) overloads).

     * Attempting to output such objects invokes implicit conversion to bool, and, for
       any non-null pointer value, the value 1 is printed (unless boolalpha was set, in
       which case true is printed).

   Character and character string arguments (e.g., of type char or const char*) are
   handled by the non-member overloads of operator<<.

     * Attempting to output a character using the member function call syntax (e.g.,
       std::cout.operator<<('c');) will call one of the overloads in (2-5) or (11-14)
       and output the numerical value.
     * Attempting to output a character string using the member function call syntax
       will call overload \fB(8)\fP and print the pointer value instead.

.SH Example


// Run this code

 #include <iomanip>
 #include <iostream>
 #include <sstream>

 int fun() { return 42; }

 int main()
 {
     std::istringstream input(" \\"Some text.\\" ");
     double f = 3.14;
     bool b = true;

     std::cout
         << fun()          // int overload (12)
         << ' '            // non-member overload
         << std::boolalpha // function overload (18)
         << b              // bool overload (1)
         << " "            // non-member overload
         << std::fixed     // function overload (18) again
         << f              // double overload (6)
         << input.rdbuf()  // streambuf overload
         << fun            // bool overload (1): there's no overload for int(*)()
         << std::endl;     // function overload (18) again

     int x = 0;
     int* p1 = &x;
     volatile int* p2 = &x;
     std::cout
         << "p1: " << p1 << '\\n'  // `const void*` overload, prints address
         << "p2: " << p2 << '\\n'; // before C++23 (P1147): bool overload :), because
             // operator<<(const void*) is not a match, as it discards the `volatile`
             // qualifier. To fix this, C++23 adds `const volatile void*` overload (9),
             // that prints the address as expected.
 }

.SH Possible output:

 42 true 3.140000 "Some text." true
 p1: 0x7ffcea766600
 p2: 0x7ffcea766600

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to          Behavior as published              Correct behavior
                      overloads (1-8,11-15) delegated the
                      insertion to                            they are converted
   LWG 117 C++98      num_put::put, but it does not have      before being passed
                      overloads for short,                    to num_put::put
                      unsigned short, int, unsigned int, and
                      float
                      overload \fB(17)\fP behaved as a
   LWG 567 C++98      FormattedOutputFunction                 it behaves as an
                      because of the resolution of LWG issue  UnformattedOutputFunction
                      60

.SH See also

   operator<<(std::basic_ostream) inserts character data or insert into rvalue stream
                                  \fI(function template)\fP
   operator<<                     performs stream input and output on strings
   operator>>                     \fI(function template)\fP
   operator<<                     performs stream output on string views
   \fI(C++17)\fP                        \fI(function template)\fP
   operator<<                     performs stream input and output of bitsets
   operator>>                     \fI(function template)\fP
   operator<<                     serializes and deserializes a complex number
   operator>>                     \fI(function template)\fP
   operator<<                     performs stream input and output on pseudo-random
   operator>>                     number engine
   \fI(C++11)\fP                        \fI(function template)\fP
   operator<<                     performs stream input and output on pseudo-random
   operator>>                     number distribution
   \fI(C++11)\fP                        \fI(function template)\fP
   put                            inserts a character
                                  \fI(public member function)\fP
   write                          inserts blocks of characters
                                  \fI(public member function)\fP
   to_chars                       converts an integer or floating-point value to a
   \fI(C++17)\fP                        character sequence
                                  \fI(function)\fP
